<!DOCTYPE html>
<html lang="en">

<head>
	<meta charset="UTF-8"/>
	<meta name="keywords" content="Script Menu, script"/>
	<link rel="stylesheet" href="../../Shared/sty/standard.css"/>
	<script defer src="../../Shared/js/toc.js"></script>
	
	<title>Automate tasks using UNIX scripts in CotEditor on Mac</title>
</head>

<body>

<h1>Automate tasks using UNIX scripts in CotEditor on Mac</h1>

<p>This page explains how to pass a document’s text to UNIX scripts that you execute from the Script menu and how to receive output from those scripts.</p>

<ul>
	<li><p>Script files must have one of the following extensions: .sh, .pl, .php, .rb, .py, .js, .awk, or .swift (regardless of the language)</p></li>
	<li><p>To run a script, make sure the script file has execute permission.</p></li>
</ul>


<section>
<h2>Refer to the document file path</h2>

<p>If the current document has been saved, its absolute file path is passed to the script as an argument.</p>
</section>


<section>
<h2>Pass text data to a script</h2>

<p>A script can receive the content of the current document through standard input (STDIN). To specify what CotEditor passes to your script, add a comment at the top of the script that contains: “<code>%%%{CotEditorXInput=<var>xxxx</var>}%%%</code>”. Replace “<code><var>xxxx</var></code>” with one of the parameters below. If you don’t specify a parameter, CotEditor passes nothing. This is the same as using “<coee>None</code>.”</p>

<ul>
	<li><p>CotEditor passes all text to scripts encoded in UTF-8.</p></li>
</ul>

<table>
	<thead>
		<tr><th>Keyword</th><th>Description</th></tr>
	</thead>
	<tbody>
		<tr><th><code>Selection</code></th><td>Pass the currently selected text.</td></tr>
		<tr><th><code>AllText</code></th><td>Pass the entire content of the document.</td></tr>
		<tr><th><code>None</code></th><td>Pass nothing (default).</td></tr>
	</tbody>
</table>
</section>


<section>
<h2>Receive output data from a script</h2>

<p>CotEditor can receive output from the script through standard output (STDOUT) and apply it to the document. To define how CotEditor handles the output, add a comment at the top of the script that contains: “<code>%%%{CotEditorXOutput=<var>xxxx</var>}%%%</code>”. Replace <code><var>xxxx</var></code> with one of the parameters below. If you don’t specify a parameter, CotEditor performs no action. This is the same as using “<code>Discard</code>.”</p>

<ul>
	<li><p>Output text must be encoded in UTF-8.</p></li>
</ul>

<table>
	<thead>
		<tr><th>Keyword</th><th>Description</th></tr>
	</thead>
	<tbody>
		<tr><th><code>ReplaceSelection</code></th><td>Replace the current selection with the output text.</td></tr>
		<tr><th><code>ReplaceAllText</code></th><td>Replace the entire content of the document with the output text.</td></tr>
		<tr><th><code>InsertAfterSelection</code></th><td>Insert the output text immediately after the current selection.</td></tr>
		<tr><th><code>AppendToAllText</code></th><td>Insert the output text at the end of the document.</td></tr>
		<tr><th><code>NewDocument</code></th><td>Create a new document and insert the output text into it.</td></tr>
		<tr><th><code>Pasteboardputs</code></th><td>Place the output text on the Clipboard.</td></tr>
		<tr><th><code>Discard</code></th><td>Do nothing (default).</td></tr>
	</tbody>
</table>
</section>


<section>
<h2>Print text to the Console</h2>

<p>Any text written to standard error (STDERR) appears in the Console window.</p>
</section>


<section>
<h2>Write a script</h2>

<p>For example, the following Python script adds a “&gt;” character to the beginning of each selected line in the current document and prints the number of processed lines to the Console.</p>

<pre class="source"><code><span class="comment">#!/usr/bin/env python3
# %%%{CotEditorXInput=Selection}%%%
# %%%{CotEditorXOutput=ReplaceSelection}%%%</span>

<span class="keyword">import</span> sys

count = 0
<span class="keyword">for</span> line <span class="keyword">in</span> sys.stdin:
    count += 1
    print(<span class="string">&quot;&gt;&quot;</span> + line.rstrip())
sys.stderr.write(<span class="string">&quot;Processed {} lines.&quot;</span>.format(count))
</code></pre>

<figure>
	<figcaption>Output to the Console</figcaption>
	<img srcset="../gfx/console@2x.png 2x" alt="[2022-05-06 18:35:00] Example Code&#x0A;Processed 5 lines."/>
</figure>

<p>You can download more sample scripts from:<br/>
<a href="https://github.com/coteditor/SampleScripts" rel="external">coteditor/SampleScripts -GitHub</a></p>
</section>


<section id="cf">
<h2>See also</h2>
<ul>
	<li><a href="script_overview.html">Automate tasks with scripting in CotEditor on Mac</a></li>
</ul>
</section>

</body>
</html>
